# Yield Distribution

This document explains how coupon distributions work end-to-end — from underlying asset cash flow to USDC in investor wallets. The system uses the ICP Master Ledger for holder snapshots, off-chain calculation for distribution amounts, and batched on-chain USDC transfers for execution.

USDC is the settlement currency throughout the product lifecycle: subscription, coupon distributions, and principal redemption. This eliminates fiat off-ramp friction for crypto-native investors while maintaining the regulated character of the underlying instrument. The stablecoin layer does not change the legal or regulatory character of the underlying bond.

Distributions are contractually scheduled per bond documentation — quarterly, semi-annual, or annual, depending on the product. The schedule is fixed at issuance and disclosed in the Pricing Supplement. There is no issuer discretion over timing.

At the scheduled distribution date, the ICP Master Ledger get_holder_snapshot(token_id, timestamp) function captures all verified token holders and their balances at a specific point in time. The snapshot is the authoritative basis for all distribution calculations.

The snapshot resolves race conditions from transfers near the distribution date. Any transfer that settles after the snapshot timestamp is excluded from that distribution period.

For the holder snapshot data model, see master-ledger.md.

Total distributable amount — derived from underlying asset cash flow, net of fees and SPV costs — is divided proportionally by each holder's balance at snapshot time.

Calculation is performed off-chain by Tortuga/Estating, not by smart contract. The smart contract executes the distribution; it does not compute it. This separation ensures that complex fee structures, withholding calculations, and multi-tranche waterfalls can be handled without on-chain computation constraints.

A batched USDC transfer transaction is constructed containing one transfer call per eligible holder: from the distribution wallet to each verified holder address. The batch is submitted to EVM. All eligible holders receive USDC in a single block.

The distribution transaction hash is recorded in the ICP Master Ledger as a YieldPayment transaction, linking the distribution event to the specific on-chain execution for audit purposes.

If an investor holds tokens on multiple chains (following a cross-chain transfer), distributions are sent to the wallet on the chain where the tokens are currently held. The Master Ledger balance tracker maintains chain-specific positions. Distributions are calculated per-chain based on the snapshot.

For multi-chain token transfer mechanics, see cross-chain-ops.md.

sequenceDiagram
    participant ASSET as Underlying Asset
    participant SPV as Luxembourg SPV
    participant PA as Paying Agent
    participant DW as Distribution Wallet
    participant ML as ICP Master Ledger
    participant CALC as Off-Chain Calculation
    participant EVM as EVM (Plume / Base / Canton)

    ASSET->>SPV: Cash flow received
    SPV->>PA: Funds transferred to paying agent
    PA->>DW: USDC conversion and transfer to distribution wallet

    DW->>ML: get_holder_snapshot(token_id, timestamp)
    ML-->>CALC: Holder balances at snapshot time

    CALC->>CALC: Calculate per-holder distribution amounts
    CALC->>EVM: Submit batched USDC transfer

    EVM-->>DW: Transfer confirmation
    DW->>ML: Record YieldPayment transaction with TX hash